Using the click manipulator

Use the click manipulator to enable users to click or tap nodes in your Kanzi application.

You can create a click manipulator using:

The click manipulator is one of the input manipulators you can use to add gesture recognition to nodes in your Kanzi application. You can assign the input manipulators through the Kanzi Engine API. See Using input manipulators.

To enable the double-click gesture for nodes, use the multi-click manipulator. See Using the multi-click manipulator.

Enabling the click gesture for a node using Kanzi Studio

To enable the click gesture for a node using Kanzi Studio:

  1. Select or create a node which you want to react to clicks.
    For example, create an Image node.
  2. In the Preview select the Node tool , right-click the node which you want to react to clicks, and in the Create click trigger with action menu select an action.
    For example, select the Write Log action.

    When you create a click trigger with an action, Kanzi Studio adds to that node:
  3. In the Node Components > Triggers configure the action that the Click trigger executes when the user sets off the trigger.
    For example, click the Write Log action and enter a message that you want to write to the Log window when the user clicks that node.
  4. In the Preview click to switch to the Interact mode.
    In the Preview when you click the node which you set to react to clicks, the trigger executes the action you selected in the Create click trigger with action in the Preview.

Enabling the click gesture for a node using the Kanzi Engine API

To enable the click gesture for a node using the Kanzi Engine API:

  1. In Kanzi Studio create a project using the Application template.
  2. In the Project create a node for which you want to enable the click gesture.
    For example, create an Empty Node 2D node, name it ClickNode, and add content to the node.
  3. In the Project select the node you created in the previous step, in the Properties add the Hit Testable property, and set it to enabled.
    When you enable this property you enable the user to pick a node.
  4. In the Project press Alt and right-click the node you created and select Alias.
    Kanzi Studio creates an alias pointing to the node from which you created the alias and adds it to the resource dictionary of its nearest ancestor node that contains a resource dictionary.
    Access alias target nodes using the # sign followed by the name of the alias.
  5. Select File > Export > Export KZB.
    Kanzi Studio creates the kzb file and configuration files from your Kanzi Studio project. Kanzi Studio stores the exported files in the <ProjectName>/Application/bin directory or the location you specify in the Binary Export Directory property in Project > Properties. The kzb file contains all nodes and resources from your Kanzi Studio project, except the resources you mark in a localization table as locale packs.
    When you run your Kanzi application from Visual Studio, your application loads the kzb file and configuration files.
  6. In Visual Studio open the solution stored in <ProjectName>/Application/configs/platforms/win32 and in the file which implements the logic of your application create and configure the click manipulator:
    1. Define the handlers for different click messages. In each handler add the code that defines the behavior for a specific click event.
      You can define the behavior also in Kanzi Studio using the click triggers. See Reacting to the click gesture you enabled with the Kanzi Engine API.
      For example, to define handlers for the ClickMessage and ClickCancelMessage messages, after the public section of the class which implements the logic of your application add:
      private:

    // Define the handler for the ClickManipulator::ClickMessage message from the nodes
    // that have an input manipulator which generates the ClickMessage message.
    void onNodeClicked(ClickManipulator::ClickMessageArguments& messageArguments)
    {
        // Add the code that handles the click event.
    }

    // Define the handler for the ClickManipulator::ClickCancelMessage message from the nodes
    // that have an input manipulator which generates the ClickCancelMessage message.
    void onNodeClickCanceled(ClickManipulator::ClickCancelMessageArguments& messageArguments)
    {
        // Add the code that handles the click cancel event.
    }
    2. In the onProjectLoaded() function create a ClickManipulator manipulator and subscribe to its messages.
      For example, add:
          virtual void onProjectLoaded() KZ_OVERRIDE
    {
        ScreenSharedPtr screen = getScreen();
        Domain* domain = getDomain();

        // Get the ClickNode node using its alias.
        NodeSharedPtr clickNode = screen->lookupNode<Node>("#ClickNode");

        // Create an input manipulator that generates click messages.
        ClickManipulatorSharedPtr clickManipulator = ClickManipulator::create(domain);

        // Add the input manipulator to the ClickNode node.
        clickNode->addInputManipulator(clickManipulator);
        
        // Subscribe to the ClickManipulator::ClickMessage message at the ClickNode node.
        // The ClickManipulator manipulator generates this message when the user clicks the node.
        clickNode->addMessageHandler(ClickManipulator::ClickMessage, bind(&MyProject::onNodeClicked, this, placeholders::_1));

        // Subscribe to the ClickManipulator::ClickCancelMessage message at the ClickNode node.
        // The ClickManipulator manipulator generates this message when the user first presses down
        // the node, then moves the pointer outside of the node area, and lifts the pointer.
        clickNode->addMessageHandler(ClickManipulator::ClickCancelMessage, bind(&MyProject::onNodeClickCanceled, this, placeholders::_1));
    }
  7. Build and run your application. See Deploying Kanzi applications.
    In the application:

Reacting to the click gesture you enabled with the Kanzi Engine API

This section explains how to use the click triggers to react to the click gesture when you enable the click gesture for a node using the Kanzi Engine API. To learn how to create a node that reacts to clicks using only Kanzi Studio, see Enabling the click gesture for a node using Kanzi Studio.

Use the Click triggers to react to the click gesture. For example, you can change the appearance of a node when the user clicks or taps that node.

Kanzi Studio has these click triggers:

To use the Click triggers:

  1. Enable the click gesture for a node using the Kanzi Engine API. See Enabling the click gesture for a node using the Kanzi Engine API.
  2. Define the behavior that you want to set with the click triggers.
    For example, create a state manager where you define the states which set the appearance of a node when different click triggers are set off. See Creating a state manager.
  3. Add and configure a click trigger:
    1. In the Project select the node to which you want to add the trigger, and in the Node Components > Triggers section add one of the click triggers.
      For example, in the Project select the node for which you enabled the click gesture and in the Node Components add the Click trigger.
    2. In the trigger you created in the previous step click Trigger Settings and in the Trigger Settings Editor disable the Set Message Handled property.
      When you disable the Set Message Handled property, this trigger intercepts the message, but does not stop it. This way you let the input manipulator handle the message.
    3. In the trigger you created, in the Add dropdown menu select an action and configure it.
      For example, select the Go to State action, and in the action settings set:
      • Item to the node for which you enabled the click gesture
      • State to the state which sets the appearance of the node when the Click trigger is set off
  4. Repeat the previous step to add and configure more click triggers.
    For example, add the Click Cancel trigger, and in the Go to State action of the trigger set State to the state which sets the appearance of the node when that trigger is set off.
  5. Select File > Export > Export KZB.
  6. Build and run your application. See Deploying Kanzi applications.
    In the application click or tap the node for which you enabled the click gesture.

Using the click manipulator in the API

For details, see the ClickManipulator class in the API reference.

See also

Handling user input

Using the multi-click manipulator

Using the long-press manipulator

Deploying Kanzi applications

Using triggers

Open topic with navigation